package cn.iocoder.yudao.module.system.service.gugu;

import cn.iocoder.yudao.module.system.controller.admin.gugu.vo.CollegeRecommendReqVO;
import cn.iocoder.yudao.module.system.controller.admin.gugu.vo.CollegeRecommendRespVO;

/**
 * 高校推荐服务接口
 *
 * @author 芋道源码
 */
public interface CollegeRecommendationService {

    /**
     * 智能推荐大学
     *
     * @param reqVO 推荐请求参数
     * @return 推荐结果
     */
    CollegeRecommendRespVO recommendColleges(CollegeRecommendReqVO reqVO);

    /**
     * 智能推荐大学（带用户ID）
     *
     * @param reqVO 推荐请求参数
     * @param userId 用户ID
     * @return 推荐结果
     */
    CollegeRecommendRespVO recommendColleges(CollegeRecommendReqVO reqVO, Long userId);

    /**
     * 计算录取概率
     *
     * @param userRank 用户位次
     * @param schoolUuid 学校UUID
     * @param majorName 专业名称
     * @param province 省份
     * @param year 年份
     * @param examType 考试类型
     * @return 录取概率（0-100）
     */
    Double calculateAdmissionProbability(Integer userRank, String schoolUuid, String majorName, 
                                       String province, Integer year, String examType);

    /**
     * 判断推荐类型
     *
     * @param probability 录取概率
     * @return 推荐类型（CHONG/WENTUO/BAODI）
     */
    String determineRecommendationType(Double probability);

    /**
     * 生成推荐理由
     *
     * @param schoolName 学校名称
     * @param majorName 专业名称
     * @param probability 录取概率
     * @param type 推荐类型
     * @param tags 学校标签
     * @return 推荐理由
     */
    String generateRecommendationReason(String schoolName, String majorName, Double probability, 
                                      String type, java.util.List<String> tags);
}
